MAPSERVE 1.5 DOCUMENTATION

Table of Contents

• Description
• Installation
  • Setting the preferences
  • A test run
• Setting up clickable imagemap graphics
  • Linking to your graphic
  • Using MapServe with MacHTTP or WebSTAR PS
  • Special Features for use with WebSTAR Commercial Servers
  • Map file format
  • Specifying URLs in the map file
  • An example MapServe map file
  • Programs to make map files
• Troubleshooting
• Other uses for MapServe
• Shareware plea

Here is an example of MapServe in action:

Clicking on the above image should launch MapServe, and retrieve a page telling you what you clicked on or near. (Note: You must view this page by retrieving it from a MacHTTP or WebSTAR server for MapServe to receive the AppleEvent information it needs to work. MapServe only works when used through MacHTTP or WebSTAR.)

Simply place the MapServe.acgi application somewhere within the folder that holds your server program. It doesn't have to be in the exact same folder as WebSTAR, but it must be in a folder the WebSTAR folder contains. It's a good idea to set up a naming scheme for your folders within your server's folder, because anyone who visits your server will get to see those names. It will help them if your file names make sense. For example, you might make a folder called "Tools" or "CGI" that can hold all your external applications for the server, or you can just use the supplied "MapServe" folder. Keep all the other files and folders with the MapServe application untill you don't need them anymore.

You should have already read through the documentation that comes with MacHTTP/WebSTAR, including the technical reference sections about calling external applications. If you haven't, take time to do so. You should also be familiar with HTML, making hypertext references ( <a href="URL"> ), and URLs and how they are specified in HTML documents.

Setting the MapServe preferences

The preferance box looks like this:

The second part of the preferences box you can leave at the default value, or you can change it to use a custom server name. If you want to customize it, you can type it in the text box. This is usefull if you want the program to give the user's browser a different server name other than the one WebSTAR knows. For example, if you have the DNS option of WebSTAR turned off, then WebSTAR sends it's name as an IP address (123.456.789.123). MapServe will then send URL's back to the browser in the form of http://123.456.789.123/blah.html. If you want it to send back the real server name, you can put this in the Preferences and it will send that in place of what WebSTAR tells it to send. (i.e. http://www.blah.com/).

Note: If you do use this option, MapServe doesn't send back any port number unless you specify it in the Prefences. (i.e. www.blah.com:8000)

A test run

This should bring up a graphic with several different colored shapes. Try clicking on one of the shapes. This should cause MapServe to start up on your server, and a file showing what you clicked on should be loaded up. If it fails for some reason, consult the section on troubleshooting later in this documentation.

Once you have a graphic file, you need to make an HTML document that uses it as an inline graphic. You can read about this in most HTML documentation. To give you a quick example, say you have a folder on your server called "Graphics" and a GIF file called "MyMap.gif" inside it. You would link to that graphic using HTML like this:

<img src="graphics/mymap.gif" ISMAP>.

The ISMAP part tells the client's browser program that the graphic is a map and it needs to send the coordinates of where the user clicked to the server.

Next you must make the graphic clickable, and specify MapServe as the program to link to when the graphic is clicked. You can do this in one of two ways, depending on what type of server you are using. If you are not using the commercial version of WebSTAR you only need to read the first of the two following sections: Using MapServe with MacHTTP or WebSTAR PS. If you are using the commercial version of WebSTARR you need to read both of the next two sections, Using MapServe with MacHTTP or WebSTAR PS and Special Features for use with WebSTAR Commercial Servers. If you're using MacHTTP or WebSTAR PS, skip the section on using MapServe with the full version of WebSTAR.

Using MapServe with MacHTTP or WebSTAR PS

Here's an example:
<a href="path/to/mapserve.cgi$mapfilepath"> </a> The mapfilepath is either a local, or a complete path to a file that specifies the information that defines the different "hotspots" in the graphic. See the Map File Format section below to learn how to define these files.

A local path would be relative to the location of the MapServe.acgi application. For example, if you have a folder name "mapfiles" in the same folder as MapServe.acgi, you can use "mapfiles/mygraphic.map" as the mapfilepath part of the URL. Or if your files are in the same folder as MapServe.acgi, you can simply use "mygraphic.map" as your path.

A complete path would begin at the beginning of your server's directory structure. This would be something like "/folder1/folder2/mygraphic.map", where you have a folder named "folder1" in the same folder as WebSTAR or MacHTTP, then there is a "folder2" inside that, and the map file you are using is called "mygraphic.map" and is inside folder2.

So the complete HTML hyperlink reference to your clickable graphic named mygraphic.gif would be:

<a href="/path/to/mapserve.cgi$mygraphic.map"><img src="mygraphic.gif" ismap></a>

Special Features for use with WebSTAR Commercial Servers

To set this up, choose "Actions" from the Configure menu in the WebSTAR Admin application. There are two parts you need to fill in, the Application, and the Action Name.

In the Application box, specify the path to the MapServe application on your server, starting with a colon (:). For example, if MapServe is in a folder called CGI in your WebSTAR folder, you'll put :cgi:mapserve.acgi in the Application part.

For the Action Name, I suggest "MAP", although you can use anything you want.

Click the Add button and then Update to close the Action dialog box. Now you need to add a suffix mapping. Open the Suffix Mapping dialog box by chossing Suffix Mappings from the Configure menu in WebSTAR Admin.

Choose the Action type that you just defined from the Action pop-up menu, then put ".MAP" in the File Suffix box. The File Type should be "TEXT" and the Creator should be "*". Put "text/html" in the MIME type field, then hit the Add button and then the Update button. Now you've made a user defined action that will tell MapServe to process the request any time a file that ends in .map is accessed.

What this allows you to do, is simply use the name of the file in the <a href> tag instead of referencing the MapServe.acgi application and then giving the path to the .map file. An example follows:

<a href="mygraphic.map"><img src="mygraphic.gif" ISMAP></a>

In this example, the .map file and the .gif graphic are in the same directory as the .html file that refers to them both. When WebSTAR receives the request for the .map file, it sees that it is supposed to use the MAP action, which makes it launch MapServe.acgi and sends it the proper AppleEvent with the path to the .map file.

To use this feature, make sure you have set the Preferences correctly.

See the WebSTAR technical reference for more info on specifying an Action.

Notes: For MacHTTP/WebSTAR, case doesn't usually matter. Other types of servers, especially UNIX, may be case sensitive. I'm usually a lazy typist when writing HTML, so I generally don't capitalize anything. (Sidenote: Actually, some browsers are case-sensitive in certain instances. For example, forms making use of the POST method don't work on some versions of NCSA Mosaic for X-Windows unless POST is capitalized, so if anyone complains that they can't get an ISMAP graphic on your server to work, check to see if the capitalization may be a cause of the problem.)

Map File Format

If you don't want to use WebMap to make your map files, or you want the added features available in MapServe that WebMap doesn't support, then you need to know the format of the map file.

Note: A .map file editor is planned for the near future. Watch the MapServe home page for updates.

The map file is a plain text document that can be made with TeachText (or SimpleText) and many other text editors. For large graphics, you could even use a database program that can export it's data as tab or space separated text, though you're much better off just editing the text file yourself. (Also, very large, complex graphics with lots of objects defined will take longer to decode.)

The general form of each line is:

shape URL coordinates

Here is an example of a line that specifies a circle with it's center located at 13,12 and an edgepoint at 45,34:

circle http://your.server/folder/file.gif 13,12 45,34

Each line can be made up of any one of the following shapes or directives:

Comments

# this is a comment

A hash mark at the beginning of a line indicates a comment

Default

default URL

This defines the default URL that should be returned if the user didn't click on an object defined elsewhere in the file. If more than one default is specified, the last one is the one that is used as the default.

Notes:

• If you define one or more Point
  point URL coordinates
  where coordinates is an X,Y pair
  If the click doesn't occur within another object (rect,circle,poly,oval) and one or more points are specified, then MapServe determines the nearest point to where the user clicked, and returns the URL for that point.

If the URL doesn't start with a slash, then it is treated as being local to the .map file (unless it contains a colon (:) character, in which case it is treated as a full URL). Local URL's in the .map file are pretty much the same as anything you can put into an <a href> tag. This means you can also use the "../" parent directory notation in a local URL.

If a file is local, MapServe appends "http://your.server.address:port" and any path information it needs to the front of what you specify as the local URL in the map file. If the port number is 80, then no port number is included in the URL. Also, you can override the servername and port number in the preferences box.

Since the fields in the map file are separated by whitespace (tabs or spaces), you cannot have any whitespace in your URL's (It's not a good idea to have any whitespace in any filenames on your web server). If you do happen to need to specify a URL for a file that has whitespace or funny characters in it's name, then you must encode that with the %xx encodings as specified in the MacHTTP/WebSTAR documentation, and several other documents specifying the use of URLs.

An example MapServe map file

# 
# Order of entries does not matter, although the map will run faster if you
# put more frequently used objects at the top. Also, a little speed will 
# be gained by placing the objects in the following order: Default, 
Rectangle, 
# Circles, Ovals, Polygons, Points.

# default URL -- MapServe example
default /mapserve/

# Blue rectangle
rect /mapserve/mapservetest/blue.html 4,5 71,39

# Green circle
circle /mapserve/mapservetest/green.html 181,57 198,57

# Orange polygon
poly /mapserve/mapservetest/orange.html 224,23 219,55 268,67 281,24 257,4 
250,36 224,23 

# Red oval
oval /mapserve/mapservetest/red.html 99,2 167,46

# Point 1
point /mapserve/mapservetest/point1.html 7,73

# Point 2
point /mapserve/mapservetest/point2.html 105,76

# Point 3
point /mapserve/mapservetest/point3.html 312,69

# Point 4
point /mapserve/mapservetest/point4.html 348,16

TROUBLESHOOTING

The map file can't be found

If MapServe can't find the .map file, it will give an error message that should include the path of the file it was looking for. This path should start with the name of the volume that the .map file resides on, and is a colon-separated path. Check to make sure that all the folder names are spelled right, and that the filename itself is spelled right.
If the volume name doesn't show up, then make sure the path to WebSTAR is set correctly in the Preferences box.

WebSTAR returns a File Not Found error.

Check to see that the URL the client is requesting goes to the MapServe.acgi program, or a .map file if you're using the user defined action method available with WebSTAR. Make sure that Mapserve.acgi exists in the location that WebSTAR expects it to be at.
If the URL showing up in the WebSTAR log window contains "mapserve.acgi$something.map?123,456" then you've run into the CERN proxy bug. What is happening here is the '$' character is being encoded wrong by either the client, or a proxy gateway that the client is using. Instead of sending the '$' in clear text, it's being sent as %24. This is a common bug with several browsers and gateways that don't conform to the HTTP standards. The only way to fix this is to either get the client programmers or proxy administrator to patch their software, or you can use the WebSTAR user defined action method.

MapServe gives a alias resolution error on startup

This can happen when you move or upgrade your WebSTAR application. You need to simply reset the path to the WebSTAR application in the preferences box.

The location that MapServe sends the client to is wrong

Check the URL where it's trying to go. If the URL is wrong, then it's probably in your .map file. Check the location in your .map file. Read through the .map file URL part of the documentation again.

MapServe is also usefull for demonstrations of the World Wide Web where you can't be connected to the Internet. Because MacHTTP/WebSTAR can be run on a Mac using only LocalTalk, you can run MapServe with it for portable demonstrations, speeches, etc.

Shareware plea

Send your shareware fees to me at the following address:

Kelly Campbell
1800 Platt, Apt. 4
Manhattan KS 66502

Please make checks payable to Kelly Campbell
I can be reached by email at CamkSoft@aol.com.

Also, I love to hear feedback (and of course bug reports) on the program, so let me know if you have any.